Chapitre 9 [edition] Rédiger et fournir les textes en RMarkdown

Les publications qui sortent du processus PROPRE contiennent des analyses de données, des tableaux et des figures. Pour la lisibilité de ces publications, il est aussi nécessaire d’y inclure des titres, des chapîtres, des paragraphes de présentation, des phrases rédigées automatiquement selon les données qu’elles décrivent… Ce sont les membres du comité éditorial [Ed] qui sont en charge de rédiger les textes à inclure dans la production.

9.1 Stratégies d’échange de contenu entre [Dev] et [Ed]

Vous allez devoir choisir et mettre en place le moyen de récupérer ces textes sans faire trop de copier-coller depuis des fichiers au format peu utilisable, depuis lesquels il est difficile de savoir ce qui est nouveau ou non. Une discussion s’impose entre les [ChfDev] et les [Ed]. Autrement dit, pas de fichiers créés avec des logiciels de traitement de texte classiques.

Les [Ed] peuvent envisager une formation à git dédiée à l’écriture collaborative de textes en Markdown. Les interfaces de RStudio et GitLab/GitHub rendent ce genre d’outils accessibles à tous. Cela simplifiera les échanges [Dev]/[Ed].

Pour cela, vous avez trois stratégies possibles de la moins contraignante pour les [Ed], à la moins contraignante pour les [Dev]. Dans tous les cas, il sera demandé aux [Ed] de rédiger les différents textes au format Markdown. C’est la raison pour laquelle, on vous parle de Markdown dès le début dans “Utiliser le format Markdown pour prendre les notes”

  • Trame dans un sous-dossier du projet de développement, nommé "trame/" (Stratégie RMarkdown)
    • Penser à ignorer ce dossier pour la construction du package : usethis::use_build_ignore("trame/")
  • Trame dans un dépôt Git à part (Stratégie RMarkdown)
  • Trame dans le Wiki GitLab (Stratégie Markdown seulement)

La première stratégie, avec le dossier inclus dans le projet de développement, est recommandée car elle permet aux [ChfDev] de réviser les modifications au même endroit que le reste du développement. S’il y a des modifications apportées, elles sont directement visibles et peuvent donner lieu à la création ou la modification d’un ticket au même endroit.

Noter qu’il y a d’un côté la trame, qui recense les besoins des [Ed], qui permet de créer les tickets de développement, qui fait partie des dossiers de développement, mais qui ne fait pas partie du package R. Et de l’autre, le corps de la publication reproductible, qui est complété au fur et à mesures des développements, avec des blocs de code R, et qui fait partie intégrante du package R (dans "inst/" a priori). Le contenu de ces deux documents a bien entendu des points communs, en particulier le plan et les différents titres.

9.2 Le langage Markdown

  • # Titre niveau 1
  • ## Titre niveau 2
  • **texte en gras**
  • _texte italique_
  • - Liste à points
  • Changer de paragraphe avec une ligne vide
## `texte au format code avec backticks`

9.3 Spécificité des stratégies RMarkdown

9.3.1 RStudio, un éditeur de texte accessible

RStudio est probablement l’outil utilisé par les développeurs pour ce projet reproductible avec R. Depuis sa version 1.4, il intègre un éditeur de texte pour les fichiers RMarkdown qui mettra les [Ed] à l’aise avec son utilisation. Pour plus d’informations, lire l’article “La nouvelle version RStudio 1.4 que l’on attendait tant”

9.3.2 Anatomie d’un RMarkdown

  • Header YAML : Il s’agit des méta-informations sur le rendu final du document. Son contenu est théoriquement réservé aux [Dev].
  • Chunk : Un chunk est un emplacement dans le document où l’on va pouvoir écrire et exécuter du code R. Ces chunks sont hautement paramétrables. Leur contenu est théoriquement réservé aux [Dev].
  • Setup Chunk : Le chunk qui va donner les options globales pour toutes les chunks. Son contenu est théoriquement réservé aux [Dev].
  • Texte : Du texte classique, écrit en langage Markdown. Ces parties sont théoriquement réservées aux [Ed].

Notez que si vous utilisez l’éditeur visuel de RStudio, l’apparence de ce document change légèrement, mais les parties sont toujours présentes.

9.3.3 Subtilité RMarkdown

Insérer du code R dans les parties de texte est possible. Le résultat de l’opération apparait comme du texte classique. C’est généralement utilisé pour insérer du texte qui dépend des résultats précédents. Par exemple: “Après avoir filtré les données, il ne reste que 12 lignes dans le tableau”. La valeur douze sera calculée et insérée ainsi dans le corps de texte :

Après avoir filtré les données, il ne reste que `r nrow(tableau)` lignes dans le tableau

Attention à ne jamais supprimer un morceau des chunks, le fichier deviendra non compilable. En cas de problème de tricotage, lisez bien le message d’erreur pour découvrir à quel endroit la compilation a planté. Vérifiez ensuite que tous les backticks sont bien présents : trois pour commencer et finir un chunk (```).

9.4 Participer à l’ajout de textes sur git

Selon la stratégie employée, vous pouvez participer à l’ajout ou la modification de textes directement dans le projet, en utilisant git. Pour cela, vous devrez suivre les instructions de “Collaboration avec git et RStudio”.